/*--------------------------------------------------------------------------------
 * Adaptive Intelligence - Windows Forms Controls Class Library
 * Version 2.00
 * 
 * Adaptive Control Base Class
 *      Provides a base class definition for Adaptive Intelligence custom controls.
 *------------------------------------------------------------------------------*/

/*--------------------------------------------------------------------------------
 * System Imports
 *------------------------------------------------------------------------------*/
using System;
using System.Text;
using System.ComponentModel;
using System.Collections.Generic;
using System.Drawing;
using System.Drawing.Drawing2D;
using System.Drawing.Imaging;
using System.Windows.Forms;

namespace Adaptive.Foundation.Windows.Forms
{
    /// <summary>
    /// Provides a base class definition for Adaptive Intelligence custom controls.
    /// </summary>
    [ToolboxItem(false)]
    public partial class AdaptiveControlBase : UserControl
    {
        /*--------------------------------------------------------------------------------
         * Private Thread Delegate Definitions
         *------------------------------------------------------------------------------*/
        #region Private Thread Delegate Definitions
        /// <summary>
        /// Internal delegate used to invoke a method from a non-UI thread.
        /// </summary>
        /// <param name="dataContent">
        /// Data content being passed to the method in the main UI thread.
        /// </param>
        private delegate void UpdateInvocation(object[] dataContent);
        #endregion

        /*--------------------------------------------------------------------------------
         * Private Member Declarations
         *------------------------------------------------------------------------------*/
        #region Private Member Declarations
        /// <summary>
        /// handle creation flag.
        /// </summary>
        private bool _handleCreated;
        #endregion

        /*--------------------------------------------------------------------------------
         * Constructor / Dispose / Destructor Methods
         *------------------------------------------------------------------------------*/
        #region Constructor / Dispose / Destructor Methods
        /// <summary>
        /// Initializes a new instance of the class.
        /// </summary>
        /// <remarks>
        /// This is the default constructor.
        /// </remarks>
        public AdaptiveControlBase()
            : base()
        {
            InitializeComponent();
        }
        /// <summary>
        /// Deallocates internally allocated objects.
        /// </summary>
        /// <param name="disposing">
        /// A value indicating whether the object is being disposed.
        /// </param>
        protected override void Dispose(bool disposing)
        {
            if (disposing)
            {
                if (components != null)
                    components.Dispose();
            }

            components = null;
            base.Dispose(disposing);
        }
        #endregion

        /*--------------------------------------------------------------------------------
         * Protected Methods / Event Methods
         *------------------------------------------------------------------------------*/
        #region Protected Methods / Event Methods
        /// <summary>
        /// Raises the <see cref="Form.Load"/> event and performs event handler assignment
        /// and initialization.
        /// </summary>
        /// <param name="e">
        /// An <see cref="EventArgs"/> event arguments instance.
        /// </param>
        protected override void OnLoad(EventArgs e)
        {
            base.OnLoad(e);

            InitializeContent();
            AssignEventHandlers();
        }
        /// <summary>
        /// Raises the <see cref="Control.HandleDestroyed"/> event.
        /// </summary>
        /// <param name="e">
        /// An <see cref="EventArgs"/> event arguments instance.
        /// </param>
        protected override void OnHandleDestroyed(EventArgs e)
        {
            RemoveEventHandlers();
            base.OnHandleDestroyed(e);
        }
        /// <summary>
        /// This method is invoked in the main UI thread to perform any neccessary
        /// updates to the UI.
        /// </summary>
        /// <remarks>
        /// Calling the related <see cref="UpdateControl()"/> is used to prevent illegal 
        /// cross-threaded UI update calls.
        /// </remarks>
        protected virtual void UpdateCurrentControlContents()
        {
        }
        /// <summary>
        /// This method is invoked in the main UI thread to perform any neccessary
        /// updates to the UI.
        /// </summary>
        /// <remarks>
        /// Calling the related <see cref="UpdateControl()"/> is used to prevent illegal 
        /// cross-threaded UI update calls.
        /// </remarks>
        /// <param name="data">
        /// The data supplied to the control to update the internal controls with.
        /// </param>
        protected virtual void UpdateCurrentControlContents(object[] data)
        {
        }
        /// <summary>
        /// Initializes the content of the control before the event handlers are assigned.
        /// </summary>
        protected virtual void InitializeContent()
        {
        }
        /// <summary>
        /// Creates and assigns the event handlers for the items contained within the control.
        /// </summary>
        protected virtual void AssignEventHandlers()
        {
        }
        /// <summary>
        /// Removes the event handlers for the items contained within the control.
        /// </summary>
        protected virtual void RemoveEventHandlers()
        {
        }
        /// <summary>
        /// Handles the evnet when the window handle is created.
        /// </summary>
        /// <param name="e">
        /// An <see cref="EventArgs"/> event arguments instance.
        /// </param>
        protected override void OnHandleCreated(EventArgs e)
        {
            _handleCreated = true;
            base.OnHandleCreated(e);
        }
        #endregion

        /*--------------------------------------------------------------------------------
         * Public Methods / Functions
         *------------------------------------------------------------------------------*/
        #region Public Methods / Functions
        /// <summary>
        /// Causes the control to update itself in the main UI thread.
        /// </summary>
        /// <remarks>
        /// This method is provided to allow a safe cross-threade UI update call.
        /// 
        /// The descendant class must provide an override of the <see cref="UpdateCurrentControlContents()"/> method.
        /// </remarks>
        public void UpdateControl()
        {
            if (_handleCreated)
                Invoke(new MethodInvoker(UpdateCurrentControlContents));    
        }
        /// <summary>
        /// Causes the control to update itself in the main UI thread.
        /// </summary>
        /// <remarks>
        /// This method is provided to allow a safe cross-threade UI update call.
        /// 
        /// The descendant class must provide an override of the <see cref="UpdateCurrentControlContents(object[])"/> method.
        /// </remarks>
        /// <param name="data">
        /// The data to pass to the update method.
        /// </param>
        public void UpdateControl(object[] data)
        {
            UpdateInvocation method = null;             //Method pointer.

            method = new UpdateInvocation(UpdateCurrentControlContents);
            method.Invoke(data);

        }
        #endregion
    }
}
